Quick Start

Get Loopar running in under 5 minutes with a single command:

npx loopar-install my-project

That's it. The installer handles everything:

1. Clones the Loopar framework
2. Installs all dependencies with Yarn
3. Sets up PM2 process manager
4. Configures Caddy for production deployments
5. Creates the default dev site
6. Starts the development server

Once complete, open your browser:

http://localhost:3000

The setup wizard will guide you through database configuration and admin account creation. After that, you'll have access to the Desk — Loopar's visual development environment.

Note: Loopar uses PM2 as its process manager. All tenants (sites) are managed through PM2, providing process monitoring, automatic restarts, and centralized control.

Prerequisites

Before installing Loopar, ensure your system meets the following requirements:

---

Required

Requirement	Version	Notes
Node.js	22.12+	LTS version recommended
Yarn	4+	Required — enabled through Corepack

⚠️ Important: Loopar is a Yarn-workspaces monorepo and requires Yarn 4+. npm and pnpm are not supported and can cause dependency-resolution errors.

---

Automatically Installed

The loopar-install command automatically installs these dependencies:

Package	Purpose
PM2	Process manager for all sites
Caddy	Reverse proxy with automatic SSL (production)

If automatic installation fails, see Manual Dependencies Installation.

---

Database (one of the following)

Database	Driver	Recommended For
MySQL / MariaDB	mysql2	Production environments
PostgreSQL	pg	Advanced features & scalability
SQLite	better-sqlite3	Development & small deployments
SQL Server	tedious	Microsoft-based infrastructure
Oracle	oracledb	Enterprise Oracle environments

---

Verify Your Environment

# Check Node.js version (must be 22.12+)
node --version

# Check Yarn version (must be 4+)
yarn --version

Installing Node.js

If you need to install or update Node.js:

# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22
nvm alias default 22

Or visit nodejs.org for direct downloads.

Enabling Yarn 4

Yarn 4 ships through Corepack, which is bundled with Node.js 16.9+:

# Enable Corepack (one time)
corepack enable

# Activate the latest stable Yarn
yarn set version stable

# Verify
yarn --version
# Should output: 4.x.x

Installation

---

Automatic Installation (Recommended)

The fastest way to get started. One command does everything:

npx loopar-install my-project

The installer will:

1. ✅ Clone the Loopar framework
2. ✅ Install all dependencies with Yarn
3. ✅ Install PM2 globally (if not present)
4. ✅ Install Caddy (if not present)
5. ✅ Create the default dev site
6. ✅ Configure PM2 ecosystem
7. ✅ Start the development server

After completion, open your browser at http://localhost:3000 to continue with the graphical setup wizard.

---

Manual Installation

For more control over the setup process or if automatic installation fails.

1. Clone the Repository

git clone https://github.com/alphabit-technology/loopar-framework.git my-project
cd my-project

2. Install Dependencies

yarn install

⚠️ Important: You must use Yarn 4+ (enabled through Corepack). npm and pnpm are not supported.

3. Start Development Server

yarn dev

This starts PM2 with the development ecosystem configuration.

---

Verify Installation

Once started, open your browser:

http://localhost:3000

You should see the Loopar setup wizard to configure your database and create your admin account.

Manual Dependencies Installation

If the automatic installer fails to install PM2 or Caddy, follow these instructions.

---

Installing PM2

PM2 is the process manager that runs all Loopar sites.

# Install PM2 globally
npm install -g pm2

# Verify installation
pm2 --version

Enable PM2 Startup (Optional)

To have PM2 start automatically on system boot:

pm2 startup
# Follow the instructions provided

# Save current process list
pm2 save

---

Installing Caddy

Caddy is required for production deployments with automatic SSL.

Ubuntu/Debian

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

CentOS/RHEL/Fedora

sudo dnf install 'dnf-command(copr)'
sudo dnf copr enable @caddy/caddy
sudo dnf install caddy

macOS

brew install caddy

Windows

Download from caddyserver.com/download or use Chocolatey:

choco install caddy

Verify Installation

caddy version
# Output: v2.x.x

Start Caddy as Service

# Linux (systemd)
sudo systemctl enable caddy
sudo systemctl start caddy

# Check status
sudo systemctl status caddy

Note: Caddy is only required for production deployments. For local development, you can skip Caddy installation.

Setup Wizard

After running npx loopar-install, navigate to http://localhost:3000 to complete the setup.

---

Step 1: Database Configuration

Select your database type and provide connection details:

Field	Description	Example
Database Type	MySQL, PostgreSQL, SQLite, SQL Server, Oracle, or MariaDB	MySQL
Host	Database server address	localhost
Port	Database port	3306
Database Name	Name of the database	loopar_db
Username	Database user	root
Password	Database password	•••••••

Tip: For quick development, use SQLite — it only requires a file path and works out of the box.

---

Step 2: Administrator Account

Create your admin credentials:

Field	Description
Full Name	Your display name
Email	Login email address
Password	Secure password (min. 8 characters)

---

Step 3: Project Information

Field	Description
Project Name	Display name for your application
Project Description	Brief description of your project

---

Completing Setup

After clicking Finish:

1. Loopar creates the database schema automatically
2. Core entities and system apps are installed
3. The dev site is fully configured
4. You're redirected to the login page

Log in with your administrator credentials to access the Desk and start building.

Architecture Overview

Loopar uses a multi-tenant architecture where all sites are managed from a central development site.

┌─────────────────────────────────────────────────────────────┐
│                     LOOPAR ARCHITECTURE                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   sites/                                                    │
│   ├── dev/              ← Development & Admin Site          │
│   │   ├── Develop apps                                      │
│   │   ├── Manage tenants (create, start, stop)              │
│   │   ├── Assign domains                                    │
│   │   └── Deploy to production                              │
│   │                                                         │
│   ├── tenant-1/         ← Production Site                   │
│   │   └── domain: myapp.com                                 │
│   │                                                         │
│   └── tenant-2/         ← Production Site                   │
│       └── domain: client.com                                │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│                         PM2                                 │
│   Manages all site processes independently                  │
├─────────────────────────────────────────────────────────────┤
│                        CADDY                                │
│   Automatic SSL & domain routing for production sites       │
└─────────────────────────────────────────────────────────────┘

Key Concepts

Concept	Description
Dev Site	The main development site where you build apps and manage tenants
Tenant	An independent site with its own database, domain, and configuration
PM2	Process manager that runs all sites independently
Caddy	Reverse proxy that handles SSL certificates and domain routing

Project Structure

Understanding Loopar's directory structure helps you navigate and extend your project effectively.

my-project/
├── apps/                    # Shared applications
│   └── loopar/              # Core Loopar app
│       ├── modules/         # Grouped entities by module
│       │   └── core/        # Core module
│       │       ├── entity/  # Entity definitions
│       │       │   ├── entity.json
│       │       │   ├── entity.js
│       │       │   └── entity.jsx
│       │       └── .../
│       └── public/          # Static assets (part of app)
├── sites/                   # Tenant sites
│   ├── dev/                 # Development site
│   │   ├── .env             # Site configuration
│   │   ├── installed-apps.json
│   │   ├── public/uploads/  # User uploads (site-specific)
│   │   └── sessions/
│   └── [tenant-name]/       # Other tenants
├── packages/                # Framework workspace packages
│   ├── loopar/              # Core framework (server + client)
│   ├── db-env/              # Knex-based data layer
│   ├── server-env/          # Express + Socket.IO server
│   ├── react-env/           # React / Vite runtime
│   ├── tailwind-env/        # Tailwind configuration
│   └── ...                  # markdown, shadcn, shared, etc.
├── loopar.ecosystem.config.mjs  # PM2 configuration
├── package.json
└── vite.config.js

Key Directories

Directory	Purpose
apps/	Shared applications available to all tenants
sites/	Individual tenant configurations and data
sites/[tenant]/public/uploads/	User-uploaded files (tenant-specific)
packages/	Internal framework packages

File Types

File	Purpose
entity.json	Field definitions, metadata, and structure
entity.js	Server-side controller (optional)
entity.jsx	Client-side React component (optional)
.env	Site-specific environment variables
installed-apps.json	Apps installed on this tenant

CLI & Process Management

Loopar ships a CLI that wraps PM2 to manage every site (tenant) process. Run commands with yarn <command> from the project root.

---

Lifecycle Commands

# Start the dev site and tail its logs
yarn dev

# Start the core site (or one site) in production mode
yarn start
yarn start my-tenant

# Stop processes (the PM2 daemon stays alive)
yarn stop
yarn stop my-tenant

# Restart processes
yarn restart
yarn restart my-tenant

# Remove a process from the PM2 registry (files are kept)
yarn delete my-tenant

# Kill all Loopar processes AND the daemon (clean slate)
yarn kill

---

Inspection

# Show every site in this Loopar daemon
yarn list      # alias: yarn status

# Tail logs for all sites, or one
yarn logs
yarn logs my-tenant

---

Operations

# Register a reboot-safe boot hook (run once after first deploy)
yarn startup

Note: Loopar runs a project-local PM2 daemon (under .pm2/ in your project). Always use the yarn commands above instead of a global pm2 — they target the correct daemon automatically.

---

Build Commands

# Full production build (client + server, versioned release)
yarn build

# Build only one side
yarn build:client
yarn build:server

---

Process Status

Status	Description
online	Site is running normally
stopped	Site was manually stopped
errored	Site crashed (check logs)
launching	Site is starting up

Tip: Most tenant management (start, stop, create, assign domain) can also be done directly from the Desk interface in the dev site, without the command line.

Tenant Management

All tenant operations are performed from the dev site through the Tenant Manager interface.

---

Accessing Tenant Manager

1. Navigate to http://localhost:3000/desk
2. Go to Core → Tenant Manager
3. View all tenants and their status

---

Creating a New Tenant

1. Click New Tenant in the Tenant Manager
2. Fill in the tenant details:

• Name: Unique identifier (e.g., my-client)
• Port: Unique port number (e.g., 3001)
• Apps: Select which apps to install

3. Save the tenant
4. The tenant is created in sites/[tenant-name]/

---

Tenant Actions

Action	Description
Start	Start the tenant process in PM2
Stop	Stop the tenant process
Restart	Restart the tenant process
Set Domain	Assign a domain for production
Deploy	Send to production with Caddy integration

---

Tenant Lifecycle

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│    Create    │ →   │  Development │ →   │  Production  │
│   (in dev)   │     │   (testing)  │     │ (with domain)│
└──────────────┘     └──────────────┘     └──────────────┘
↓                     ↓
localhost:3001        myapp.com
NODE_ENV=dev         NODE_ENV=prod

Production Deployment

Deploying a tenant to production is done entirely from the dev site interface.

---

Prerequisites

1. Caddy running on your server
2. Domain configured to point to your server IP
3. Ports 80/443 open for HTTP/HTTPS traffic

---

Deploying a Tenant

Step 1: Configure the Tenant

1. Open Tenant Manager in the dev site
2. Select the tenant you want to deploy
3. Fill in production settings:

• Domain: myapp.com or subdomain.myapp.com
• Production Mode: Enable

Step 2: Deploy

1. Click Set on Production (or Deploy)
2. Loopar will automatically:

• Register the domain in Caddy
• Configure automatic SSL via Let's Encrypt
• Restart the tenant with NODE_ENV=production
• Enable production optimizations

---

What Happens Behind the Scenes

┌─────────────────────────────────────────────────────────────┐
│                  DEPLOYMENT PROCESS                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. Validate domain configuration                           │
│                    ↓                                        │
│  2. Register domain in Caddy reverse proxy                  │
│                    ↓                                        │
│  3. Caddy obtains SSL certificate (Let's Encrypt)           │
│                    ↓                                        │
│  4. Update tenant environment (NODE_ENV=production)         │
│                    ↓                                        │
│  5. Restart PM2 process with production config              │
│                    ↓                                        │
│  6. Tenant is live at https://myapp.com                     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

Production vs Development

Aspect	Development	Production
NODE_ENV	development	production
HMR (Hot Reload)	✅ Enabled	❌ Disabled
Watch Mode	✅ Enabled	❌ Disabled
Bundle	Unoptimized	Minified & optimized
SSL	Not required	Automatic via Caddy
Domain	localhost:PORT	Custom domain

---

Independent Tenant Modes

Each tenant can run in its own mode independently:

sites/
├── dev/        → NODE_ENV=development (always)
├── staging/    → NODE_ENV=development (testing)
├── client-a/   → NODE_ENV=production  (live)
└── client-b/   → NODE_ENV=production  (live)

This allows you to have some tenants in production while others remain in development mode for testing.

Troubleshooting

Common issues and their solutions.

---

Yarn Version Issues

Error: This project requires Yarn 4+

Solution: Enable Yarn 4 through Corepack:

corepack enable
yarn set version stable
yarn --version
# Should output: 4.x.x

If an old global Yarn is shadowing the project version:

corepack enable
yarn set version stable

---

PM2 Process Not Starting

# Check PM2 logs for errors
pm2 logs dev --lines 100

# Check if port is already in use
lsof -i :3000

# Restart with fresh state
pm2 delete all
yarn dev

---

Database Connection Failed

Error: Access denied for user 'root'@'localhost'

Solutions:

1. Verify database credentials in the setup wizard
2. Ensure the database server is running
3. Check that the database user has proper permissions:

CREATE DATABASE loopar_db;
GRANT ALL PRIVILEGES ON loopar_db.* TO 'user'@'localhost';
FLUSH PRIVILEGES;

---

PM2 Not Found

Command 'pm2' not found

Solution: Install PM2 manually:

npm install -g pm2
pm2 --version

---

Caddy Not Registering Domain

# Check if Caddy is running
sudo systemctl status caddy

# Check Caddy logs
journalctl -u caddy -f

# Verify Admin API is accessible
curl http://localhost:2019/config/

Common causes:

• Caddy not running
• Port 2019 blocked
• Domain DNS not pointing to server

---

SSL Certificate Not Generated

Requirements for automatic SSL:

• Domain must resolve to your server's IP
• Ports 80 and 443 must be open
• Caddy must be able to reach Let's Encrypt

# Test domain resolution
dig myapp.com

# Check if ports are open
sudo ufw status

---

Tenant Shows "Stopped" Status

# Check tenant logs
pm2 logs tenant-name --lines 50

# Restart the tenant
pm2 restart tenant-name

# Or restart from Desk interface

---

Node Version Mismatch

Error: The engine "node" is incompatible

Solution: Update Node.js to version 22+:

# Using nvm
nvm install 22
nvm use 22
nvm alias default 22

Next Steps

Congratulations! You have Loopar running. Here's what to explore next:

---

Learn the Fundamentals

1. Concepts — Understand Entities, Apps, Modules, and Builders
2. Learn — Step-by-step tutorials for building applications

---

Build Your First App

1. Navigate to http://localhost:3000/desk
2. Go to App → New App
3. Create your first Entity
4. Design a form using drag-and-drop
5. View your data in the auto-generated list view

---

Create Your First Tenant

1. Go to Core → Tenant Manager
2. Create a new tenant with a unique port
3. Install your app on the tenant
4. Test in development mode
5. When ready, assign a domain and deploy to production

---

Explore the Desk

Section	Purpose
App	Create and manage applications
Module	Organize entities into modules
Entity	Define data models and views
Page	Build custom pages and layouts
Tenant Manager	Create and manage tenant sites
Settings	Configure system settings

---

Join the Community

• ⭐ Star us on GitHub
• 🐛 Report issues or request features
• 🤝 Contribute to the project

---

Tip: The best way to learn Loopar is by building. Start with a simple app in the dev site, then create a tenant and deploy it. The visual environment makes it easy to experiment!